<!doctype html>
<html>
  <head>
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="chrome=1">
    <title>Webcam Capture in Java</title>
    <link rel="stylesheet" href="stylesheets/styles.css">
    <link rel="stylesheet" href="stylesheets/pygment_trac.css">
    <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js"></script>
    <script src="javascripts/main.js"></script>
    <script src="examples/google-code-prettify/prettify.js"></script>
    <link rel="stylesheet" href="examples/google-code-prettify/sons-of-obsidian-2.css">
    <!--[if lt IE 9]>
      <script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
    <![endif]-->
    <meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no">
  </head>
  <body>
  
      <a href="https://github.com/sarxos/webcam-capture"><img style="position: absolute; top: 0; right: 0; border: 0; z-index: 100;" src="https://s3.amazonaws.com/github/ribbons/forkme_right_red_aa0000.png"></a>

      <header>
        <h1>Webcam Capture</h1>
        <p>Generic Webcam Java Utility</p>
      </header>

      <div id="banner">
        <span id="logo"></span>

        <a href="https://github.com/sarxos/webcam-capture" class="button fork"><strong>GitHub</strong></a>
        <div class="downloads">
          <span>Download:</span>
          <ul>
            <li><a href="http://repo.sarxos.pl/maven2/com/github/sarxos/webcam-capture/0.3.10-RC6/webcam-capture-0.3.10-RC6-dist.zip" class="button">ZIP</a></li>
          </ul>
        </div>
      </div><!-- end banner -->

    <div class="wrapper">
      <nav>
        <ul></ul>
      </nav>
      <section>



<h1>Webcam Capture</h1>

<p>
The goal of this project is to provide really simple webcam API allowing you to use your
build-in or external (connected via USB) webcams or IP / network cameras directly from the 
Java code. Project provides very basic webcam 
interface and a set of additional <i>drivers</i> which can be used to replace default, build-in
drivers to extend and/or replace default functionality.
</p>

<p>Continous Integration build status (Travis CI):</p>

<p>
<a href="http://travis-ci.org/sarxos/webcam-capture"><img src="https://secure.travis-ci.org/sarxos/webcam-capture.png?branch=master" alt="Build Status" title="" /></a>
</p>


<a class="anchor" name="requirements"></a>
<h3>Requirements</h3>

<p>
<ul>
<li>Java 6 (or higher),</li>
<li>Webcam connected and configured,</li>
<li>On Linux system, the <i>libv4l</i> and <i>libv4lconvert</i> must be installed.
<li>In case of IP / network cameras, Internet access is required,</li>
</ul>
</p>

<a class="anchor" name="core-features"></a>
<h3>Core Features</h3>

<p>
<ul>
<li><b>Simple and thread-safe API</b> - it's really enough to write only few lines of code to start capturing camera images.</li>
<li><b>Standalone</b> - no additional software has to be installed to use it (except the <i>libv4l</i> and <i>libv4lconvert</i> which are required on Linux).</li>
<li><b>System independent</b> - it will run without problems on most widely used operating systems. It was confirmed to work fine on Windows (2k/XP/Vista/7/8, both 32- and 64-bit), Linux (both 32- and 64-bit), ARM devices (both armel and armhf), and Mac OS X.</li>
<li><b>Implementation independent</b> - write your code once and if you find better or more suitable capturing framework in the future, just replace the driver or wrap the framework through the WebcamDriver class and don't care about any code changes.</li>
<li><b>Resources management</b> - you do not have to remember to deallocate resources used by your capturing device, the library core will always do that for you.</li>
<li><b>Motion detector</b> - simple motion detector is delivered within the library.</li>
<li><b>Available in Maven Central</b> - it is available in Maven Central and therefore will not suddenly disappear.</li>
<li><b>Re-streamer</b> - simple JPEG/MJPEG re-streamer is build in, just run it and enjoy hosting your live stream.</li>
<li><b>Swing ready</b> - contains Swing components used to display images, shipped together with painter API and thread-safe API, which prevents Swing EDT from experiencing blocking issues when using camera device.</li>
</ul>
</p>


<a class="anchor" name="contribute"></a>
<h2>Contribute</h2>

<p>
If you have spare time, knowledge or even some small money amount 
to spent, you can help developing awesome Webcam Capture API and make
it even better! Several kinds of contributions are very welcome:
</p>

<p>
<ul>
<li><b>Report</b> - if you found a bug or you have came-up with 
some fantastic feature which 
can make Webcam Capture a better API to use, don't hesitate to 
<a href="https://github.com/sarxos/webcam-capture/issues/new">create new issue</a> 
where you can describe in details what the problem is, or what would you
like to improve.</li>
<li><b>Test</b> - since Webcam Capture use native code, it's very 
hard to cover all supported operating systems. I'm always testing it
on 64-bit Ubuntu Linux, Windows XP and Vista (both 32-bit), but I
have no possibility to test on Raspberry Pi, Mac OS and 32-bit Linux.</li>
<li><b>Code</b> - if you know Java or C++ you can help developing 
Webcam Capture by <a href="https://github.com/sarxos/webcam-capture">forking repository</a>
and sending pull requests. </li>
<li><b>Donate</b> - people have expressed a wish to donate a little
money. Donating won't get you anything special, other than a warm
feeling inside, and possibly urge me to produce more freely 
available material for Webcam Capture project. You can 
donate via PayPal by sending money to songo.bercik@interia.pl, or 
by the donation button below.<br/><br/>

<form action="https://www.paypal.com/cgi-bin/webscr" method="post">
<input type="hidden" name="cmd" value="_s-xclick">
<input type="hidden" name="hosted_button_id" value="UYMENK76CSYZU">
<input type="image" src="https://www.paypalobjects.com/en_GB/i/btn/btn_donate_SM.gif" border="0" name="submit" alt="PayPal � The safer, easier way to pay online.">
<img alt="" border="0" src="https://www.paypalobjects.com/pl_PL/i/scr/pixel.gif" width="1" height="1">
</form>

</li>
</ul>
</p>


<a class="anchor" name="how-to-start"></a>
<h2>How To Start</h2>

<p>
<i>Webcam Capture</i> is avilable in Maven Central, so if you can add its dependency to your
project if you are using one of the dependency manager:
</p>

<h3>Maven</h3>

<pre class="prettyprint prettyprinted language-xml linenums">
&lt;dependency&gt;
    &lt;groupId&gt;com.github.sarxos&lt;/groupId&gt;
    &lt;artifactId&gt;webcam-capture&lt;/artifactId&gt;
    &lt;version&gt;0.3.9&lt;/version&gt;
&lt;/dependency&gt;
</pre>

<h3>No Dependency Manager?</h3>

<p>
Download ZIP file containing complete API reference, required JARs, sources and examples
(link is visible at the right top corner of this page), uncompress, and add <i>webcam-capture-[version].jar</i>
and all JARs under <i>libs</i> directory to your project's classpath:
</p>

<h2>Additional Drivers</h2>

<p>
The driver is something that wraps the capturing framework and make it available 
for the Webcam Capture API. Driver can be replaces and currently <i>Webcam Capture</i>
supports the following ones:
</p>



<h3>IP Camera Driver</h3>

<p>
The IP camera driver allows Webcam Capture API to 
handle pictures from remote IP cameras supporting JPEG and/or MJPEG (Motion JPEG)
compression. It contains generic IP camera device interface, but can be customized to 
support more sophiscicated functions like tilt, angle, etc. For more information about
already supported models, on info of how to extend the default IP camera device, to 
find more detailed examples, use-cases, etc, please follow to the dedicated Github site
available <b><a href="https://github.com/sarxos/webcam-capture/tree/master/webcam-capture-drivers/webcam-capture-driver-ipcam">here</a></b>.
</p>

<p>
This driver is available in Maven Central.
</p>



<h3>JMF/FMJ Driver</h3>

<p>
This driver utilizes JMF capabilities to access webcam and can be used as a replacement 
for default, build-in driver. Its advantage is the fact it's pretty fast, but unfortunately, 
from the other hand, it requires <a href="http://www.oracle.com/technetwork/java/javase/download-142937.html">JMF</a> 
to be installed on your PC.
If you do not want to use JMF (due to e.g. licensing issues), you can choose 
<a href="http://fmj-sf.net/">FMJ</a>, which is a freeware replacement for JMF.
</p>

<p>
<b>NOTE!</b> Please be aware of the fact that both JMF (from Oracle) and FMJ 
(from Larson Technologies Inc.) are not being maintained any more!
</p>

<p>
This driver is available in Maven Central.
</p>



<h3>OpenIMAJ Driver</h3>

<p>
This driver utilizes the awesome <a href="http://sourceforge.net/p/openimaj/home/OpenIMAJ/">OpenIMAJ</a>
framework capabilities to access webcam devices and can be used as a replacement 
for default build-in driver (it's actually pretty the same). Its advantage is 
the fact it's pretty fast, supports 
multiple platforms, but disadvantage is the size of required 3<sup>rd</sup> party 
JARs (around ~20MB). Default build-in driver uses OpenIMAJ natives to support 
video grabbing, but id does not require all those additional JARs.
</p>

<p>
This driver is <b>NOT</b> available in Maven Central, but it can be used in Maven build.
In such a case one have to add those repositories to project's POM:
</p>

<pre class="prettyprint prettyprinted language-xml linenums">
&lt;repositories&gt;
    &lt;repository&gt;
        &lt;id&gt;OpenIMAJ maven repository&lt;/id&gt;
        &lt;url&gt;http://maven.openimaj.org/&lt;/url&gt;
    &lt;/repository&gt;
    &lt;repository&gt;
        &lt;id&gt;OpenIMAJ Snapshots maven repository&lt;/id&gt;
        &lt;url&gt;http://snapshots.openimaj.org&lt;/url&gt;
    &lt;/repository&gt;
&lt;/repositories&gt;
</pre>



<h3>LTI-CIVIL Driver</h3>

<p>
This driver utilizes  <a href="http://lti-civil.org/">LTI-CIVIL</a> project
capabilities to access PC webcam and can be used as a replacement 
for default build-in driver. LTI-CIVIL supports Windows, Linux and MAC OS platforms.
For Mac OS it utilizes QTJ framework capabilities. For other ones it uses precompiled 
natives.
</p>

<p>
<b>NOTE!</b> Be aware of the fact that LTI-CIVIL framework not being maintained any
more by its owner, so all the issues found within this framework will <b>NOT</b> be fixed!
</p>

<p>
This driver is available in Maven Central.
</p>




<h3>OpenCV Driver</h3>

<p><b>WARNING: EXPERIMENTAL STUFF!</b></p>

<p>
This driver utilizes <a href="http://code.google.com/p/javacv/">OpenCV Java bindings</a>
to access webcam devices. It can be used as a replacement 
for default build-in driver. Its advantage is quite stable interface, but unfortunately
it requires quite huge (around ~100MB) pre-installed OpenCV bundle.
</p>

<p>
This driver is <b>NOT</b> available in Maven Central, but it can be used in Maven build.
In such a case user has to add those repositories to project's POM:
</p>

<pre class="prettyprint prettyprinted language-xml linenums">
&lt;repositories&gt;
    &lt;repository&gt;
        &lt;id&gt;javacv&lt;/id&gt;
        &lt;url&gt;http://maven2.javacv.googlecode.com/git&lt;/url&gt;
    &lt;/repository&gt;
    &lt;repository&gt;
        &lt;id&gt;kevoree&lt;/id&gt;
        &lt;url&gt;http://maven.kevoree.org/release&lt;/url&gt;
    &lt;/repository&gt;
&lt;/repositories&gt;
</pre>

<h3>VLC Driver</h3>
]
<p>
This driver utilizes Caprica <a href="https://github.com/caprica/vlcj">VLCj</a> 
Java wrapper for Videolan <a href="http://www.videolan.org/vlc/">VLC</a> 
media player to access PC webcam and can be used as a replacement 
for default build-in driver. It requires VLC media player to be 
pre-installed on the system where driver will be used. More informations on
how to use this driver can be found on <a href="https://github.com/sarxos/webcam-capture/tree/master/webcam-capture-drivers/webcam-capture-driver-vlcj">this</a> 
dedicated Github page. Its disadvantage is very poor performance.
</p>

<p>
This driver is <b>NOT YET</b> available in Maven Central (but it will be).
</p>



<h2>Compatibility</h2>

<p>
API confirmed to be perfectly running on the following systems (please
report at the project page if you tested it on other system, just 
create new issue for that purpose):
</p>

<p>
<ul>
<li>Windows XP, 32-bit</li>
<li>Windows Vista, 32-bit</li>
<li>Windows 7, 32- and 64-bit</li>
<li>Windows 8, 32- and 64-bit</li>
<li>Ubuntu 12.04, 32- and 64-bit</li>
<li>Ubuntu 12.10, 32- and 64-bit</li>
<li>Ubuntu 13.04, 32- and 64-bit</li>
<li>Mac OS Snow Leopard</li>
<li>Raspberry Pi @ Arch Linux, both armel and armhf</li>
<li>Raspberry Pi @ Raspbian, both armel and armhf</li>
</ul>
</p>

<p>
However some problems has been detected on Raspberry Pi where API is not able
to load OpenIMAJGrabber.so. To workaround this problem one must to extract 
webcam-capture JAR, go to the directory com/github/sarxos/webcam/ds/buildin/lib 
and get the file for the appropriate Linux and copy it to the path where system
can Load it.
</p>


<h1>Examples</h1>

Just a bunch of small examples.


<h3>Capture Image</h3>

<p>To capture single image and save it to disk:</p>

<pre class="prettyprint prettyprinted language-java linenums">
Webcam webcam = Webcam.getDefault();
webcam.open();
BufferedImage image = webcam.getImage();
ImageIO.write(image, "PNG", new File("test.png"));
</pre>

<p>If you have more then one webcam connected to your computer:</p>

<pre class="prettyprint prettyprinted language-java linenums">
Webcam laptop = Webcam.getWebcams().get(0);
Webcam kitchen = Webcam.getWebcams().get(1);
Webcam roof = Webcam.getWebcams().get(2);
</pre>


<h3>Detect Motion</h3>

<p>To detect motion with your webcam - loop solution:</p>

<pre class="prettyprint prettyprinted language-java linenums">
WebcamMotionDetector detector = new WebcamMotionDetector(Webcam.getDefault());
detector.setInterval(100); // one check per 100 ms (10 FPS)
detector.start();

while (true) {
    if (detector.isMotion()) {
        System.out.println("Detected motion I, alarm turn on you have");
    }
    Thread.sleep(500);
}
</pre>

<p>To detect motion with webcam - listener solution:</p>

<pre class="prettyprint prettyprinted language-java linenums">
public class DetectMotionExample implements WebcamMotionListener {

    WebcamMotionDetector detector = new WebcamMotionDetector(Webcam.getDefault());

    public DetectMotionExample() {
        detector.setInterval(100); // one check per 100 ms (10 FPS)
        detector.addMotionListener(this);
        detector.start();
    }

    @Override
    public void motionDetected(WebcamMotionEvent wme) {
        System.out.println("Detected motion I, alarm turn on you have");
    }

    public static void main(String[] args) throws IOException {
        new DetectMotionExample();
        System.in.read(); // keeps your program open
    }
}
</pre>

<h3>Swing Support</h3>

<p>
You can display image from webcam in Swing JPanel. There is a special component
designed for this.
</p>

<pre class="prettyprint prettyprinted language-java linenums">
JFrame window = new JFrame("Test Webcam Panel");
window.add(new WebcamPanel(Webcam.getDefault()));
window.pack();
window.setVisible(true);
window.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
</pre>

<h3>Display Image From IP / Network Camera</h3>

<p>
To use Webcam Capture together with IP or network camera you have to add 
<a href="https://github.com/sarxos/webcam-capture/tree/master/webcam-capture-driver-ipcam">IP / network camera driver</a>
to your Webcam Capture project.
</p>

<pre class="prettyprint prettyprinted language-java linenums">
IpCamDevice ipcam = new B7210("B7210", "114.32.216.24");
ipcam.setAuth(new IpCamAuth("demo", "demo"));
ipcam.setSize(B7210.SIZE_QVGA);

IpCamDriver driver = new IpCamDriver();
driver.register(ipcam);

Webcam.setDriver(driver);

WebcamPanel panel = new WebcamPanel(Webcam.getDefault());
panel.setFPS(0.5); // 1 frame per 2 seconds

JFrame f = new JFrame("Night Tree Somewhere");
f.add(panel);
f.pack();
f.setVisible(true);
f.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
</pre>

<p>
More IP / network camera examples are available in Github project's page.
</p>


<h3>Development Troubleshooting</h3>

<p>
In the development phase you will probably kill running application many
time (by stop button in Eclipse, Netbeans or other IDE), or by calling 
<i>kill -TERM &lt;pid&gt;</i> command from CLI. You have to be aware that
killing running application when Webcam Capture is already running can have 
unwanted side-effects, such as:
</p>

<ul>
<li>Devices cannot be discovered,</li>
<li>Devices discovery hangs applciation or operating system,</li>
<li>Cannot open webcam device,</li>
<li>Cannot capture image from webcam,</li>
<li>Webcam found but later does not exists,</li>
<li>Etc.</li>
</ul>

<p>
All those issues arose from the same root cause - memory has not been 
properly deallocated in the native layer. That's because you killed application
instead of closing it gracefully.
</p>

<p>
However, there is a solution for this problem. For such purpose special TERM 
signal handler has been implemented, and you can enable it before you actually
start using Webcam Capture API. This can be done by calling this code (please 
<b>make sure</b> to call it before you use any other method!):
</p>

<pre class="prettyprint prettyprinted language-java linenums">
Webcam.setTermSignalHandler(true);
</pre>

<p>
<b>IMPORTANT NOTE!</b> This is development setting and <b>shall not</b> be used
in production code!!! It modified the way of how JVM terminates its process, so
depending on the system there can be some unknown side-effects. Also features used
in this handler are undocumented and can be removed in further Java releases
without prior notification.
</p>



<h3>Logging</h3>

<p>
Logging has been implemented via SLF4J API, so all you need to do 
is to add specific implementation and create configuration file.
</p>

<h4>Logging Example With Logback Library</h4>

<p>
This paragraph describes in short how to use <a href="http://logback.qos.ch/">Logback</a> 
to enable logs from Webcam Capture API.
</p>

<p>
Go to <a href="http://logback.qos.ch/">Logback home page</a> and download
ZIP files containing all required JARs. Extract ZIP and add those files into
your classpath:
</p>

<ul>
<li>logback-classic-<b>[version]</b>.jar</li>
<li>logback-core-<b>[version]</b>.jar</li>
</ul>

<p>
NOTE! The <b>[version]</b> is current Logback release signature (e.g. 1.0.9).
</p>

<p>
Create <b>logback.xml</b> file and put this content inside:
</p>

<pre class="prettyprint prettyprinted language-xml linenums">
&lt;configuration scan=&quot;true&quot; scanPeriod=&quot;30 seconds&quot;&gt;
	&lt;appender name=&quot;STDOUT&quot; class=&quot;ch.qos.logback.core.ConsoleAppender&quot;&gt;
		&lt;layout class=&quot;ch.qos.logback.classic.PatternLayout&quot;&gt;
			&lt;Pattern&gt;%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n&lt;/Pattern&gt;
		&lt;/layout&gt;
	&lt;/appender&gt;
	&lt;root level=&quot;debug&quot;&gt;
		&lt;appender-ref ref=&quot;STDOUT&quot; /&gt;
	&lt;/root&gt;
&lt;/configuration&gt;
</pre>

<p>
When you include this file in your classpath, it will be discovered
automatically, but you can also load it manually by calling:
</p>

<pre class="prettyprint prettyprinted language-java linenums">
WebcamLogConfigurator.configure("path/to/logback.xml");
</pre>


<h2>More Examples?</h2>

<p>
There are more examples available in <b>src/example</b>, don't forget to 
check them - please follow to the <a href="https://github.com/sarxos/webcam-capture">Github Project's Page</a> where <i>Webcam Capture</i>
source code is stored! Here are the examples links:
</p>

<ul>
<li><a href="https://github.com/sarxos/webcam-capture/tree/master/webcam-capture/src/example/java">Small & trivial examples</a></li>
<li><a href="https://github.com/sarxos/webcam-capture/tree/master/webcam-capture-examples">Large & complex examples</a></li>
</ul>


<h1>License</h1>

<p>Copyright (C) 2012 - 2013 Bartosz Firyn</p>
<p>Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:</p>
<p>The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.</p>
<p>THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.</p>



      </section>
      <footer>
        <p>Maintained by <a href="https://github.com/sarxos">SarXos</a></p>
      </footer>
    </div>
    <!--[if !IE]><script>fixScale(document);</script><!--<![endif]-->
    <script type="text/javascript">
    prettyPrint();
    </script>

  </body>
</html>
